מבנה חבילת Python: Setup.py מול Pyproject.toml - מדריך מקיף

במשך שנים, קובץ ה-setup.py היה אבן היסוד של ניהול חבילות Python. אולם, הנוף התפתח, ו-pyproject.toml הופיע כחלופה מודרנית. מדריך מקיף זה בוחן את ההבדלים בין שתי הגישות הללו, ועוזר לך להבין איזו מהן מתאימה לפרויקט שלך וכיצד לנהל ביעילות את חבילות ה-Python שלך.

הבנת היסודות

מהי חבילת Python?

חבילת Python היא דרך לארגן ולהפיץ את קוד ה-Python שלך. היא מאפשרת לך לקבץ מודולים קשורים בהיררכיה של ספריות, מה שהופך את הקוד שלך למודולרי יותר, ניתן לשימוש חוזר ולתחזוקה קלה יותר. חבילות חיוניות לשיתוף הקוד שלך עם אחרים ולניהול תלויות בפרויקטים שלך.

תפקיד מטא-נתוני חבילה

מטא-נתוני חבילה מספקים מידע חיוני על החבילה שלך, כגון שמה, גרסתה, מחברה, תלויות ונקודות כניסה. מטא-נתונים אלה משמשים מנהלי חבילות כמו pip להתקנה, שדרוג וניהול החבילות שלך. היסטורית, setup.py הייתה הדרך העיקרית להגדיר מטא-נתונים אלה.

Setup.py: הגישה המסורתית

מהו Setup.py?

setup.py הוא סקריפט Python המשתמש בספריית setuptools כדי להגדיר את המבנה והמטא-נתונים של החבילה שלך. זהו קובץ המבוצע באופן דינמי, כלומר הוא מריץ קוד Python כדי להגדיר את החבילה.

רכיבים עיקריים של Setup.py

קובץ setup.py טיפוסי כולל את הרכיבים הבאים:

• שם החבילה: שם החבילה שלך (לדוגמה, my_package).
• גרסה: מספר הגרסה של החבילה שלך (לדוגמה, 1.0.0).
• פרטי מחבר ותחזוקאי: פרטים על מחבר ותחזוקאי החבילה.
• תלויות: רשימה של חבילות אחרות שהחבילה שלך תלויה בהן (לדוגמה, requests >= 2.20.0).
• נקודות כניסה: הגדרות עבור סקריפטים של שורת פקודה או נקודות כניסה אחרות לחבילה שלך.
• נתוני חבילה: קבצים שאינם קוד (לדוגמה, קבצי תצורה, קבצי נתונים) שאמורים להיכלל בחבילה.

דוגמה ל-Setup.py

            from setuptools import setup, find_packages

setup(
    name='my_package',
    version='1.0.0',
    author='John Doe',
    author_email='john.doe@example.com',
    description='A simple Python package',
    packages=find_packages(),
    install_requires=[
        'requests >= 2.20.0',
    ],
    entry_points={
        'console_scripts': [
            'my_script = my_package.module:main',
        ],
    },
    classifiers=[
        'Programming Language :: Python :: 3',
        'License :: OSI Approved :: MIT License',
        'Operating System :: OS Independent',
    ],
)

            

              
                Copy
              
            
          

יתרונות Setup.py

• היכרות: זוהי הגישה המסורתית והמוכרת, ולכן מפתחים רבים כבר מכירים אותה.
• גמישות: מכיוון שמדובר בסקריפט Python, הוא מציע רמה גבוהה של גמישות. ניתן לבצע לוגיקה מורכבת ולהתאים אישית את תהליך הבנייה לפי הצורך.
• הרחבה: Setuptools מספקת קבוצה עשירה של תכונות וניתנת להרחבה באמצעות פקודות והרחבות מותאמות אישית.

חסרונות Setup.py

• ביצוע דינמי: האופי הדינמי של setup.py יכול להוות סיכון אבטחתי, מכיוון שהוא מריץ קוד שרירותי במהלך תהליך הבנייה.
• תלויות מרומזות: setup.py מסתמך לעיתים קרובות על תלויות מרומזות, כגון setuptools עצמה, מה שעלול להוביל לחוסר עקביות ושגיאות.
• מורכבות: עבור פרויקטים מורכבים, setup.py יכול להפוך לגדול וקשה לתחזוקה.
• תצורת הצהרתית מוגבלת: רוב מטא-נתוני החבילה מוגדרים באופן אימפרטיבי ולא הצהרתי, מה שמקשה על ההבנה.

Pyproject.toml: החלופה המודרנית

מהו Pyproject.toml?

pyproject.toml הוא קובץ תצורה המשתמש בפורמט TOML (Tom's Obvious, Minimal Language) כדי להגדיר את מערכת הבנייה והמטא-נתונים של החבילה שלך. זוהי גישה הצהרתית, כלומר אתה מציין מה ברצונך להשיג, ולא כיצד להשיג זאת.

סעיפים עיקריים ב-Pyproject.toml

• [build-system]: מגדיר את מערכת הבנייה לשימוש (לדוגמה, setuptools, poetry, flit).
• [project]: מכיל מטא-נתונים על הפרויקט, כגון שמו, גרסתו, תיאורו, מחבריו ותלויותיו.
• [tool.poetry] או [tool.flit]: סעיפים לתצורות ספציפיות לכלי (לדוגמה, Poetry, Flit).

דוגמה ל-Pyproject.toml (עם Setuptools)

            [build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "my_package"
version = "1.0.0"
description = "A simple Python package"
authors = [
    { name = "John Doe", email = "john.doe@example.com" }
]
dependencies = [
    "requests >= 2.20.0",
]

[project.scripts]
my_script = "my_package.module:main"

[project.optional-dependencies]
dev = [
    "pytest",
    "flake8",
]

[project.classifiers]
classifiers = [
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: MIT License",
    "Operating System :: OS Independent",
]

[project.urls]
homepage = "https://example.com"
repository = "https://github.com/example/my_package"


            

              
                Copy
              
            
          

דוגמה ל-Pyproject.toml (עם Poetry)

            [tool.poetry]
name = "my_package"
version = "1.0.0"
description = "A simple Python package"
authors = ["John Doe <john.doe@example.com>"]
license = "MIT"
readme = "README.md"

[tool.poetry.dependencies]
python = ">=3.7,<3.12"
requests = ">=2.20.0"

[tool.poetry.dev-dependencies]
pytest = "^6.0"
flake8 = "^3.9"

[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"

            

              
                Copy
              
            
          

יתרונות Pyproject.toml

• תצורה הצהרתית: pyproject.toml מספק דרך הצהרתית להגדיר את מטא-נתוני החבילה שלך, מה שמקל על ההבנה והתחזוקה.
• מערכת בנייה סטנדרטית: הוא מציין את מערכת הבנייה לשימוש, מה שמבטיח בנייה עקבית בסביבות שונות.
• ניהול תלויות משופר: כלים כמו Poetry ו-Pipenv משתלבים בצורה חלקה עם pyproject.toml כדי לספק תכונות חזקות לניהול תלויות.
• סיכוני אבטחה מופחתים: מכיוון שהוא קובץ תצורה סטטי, הוא מבטל את סיכוני האבטחה הקשורים לביצוע דינמי של קוד במהלך תהליך הבנייה.
• אינטגרציה עם כלים מודרניים: pyproject.toml הוא הסטנדרט לכלי אריזת Python מודרניים כמו Poetry, Pipenv ו-Flit.

חסרונות Pyproject.toml

• עקומת למידה: ייתכן שמפתחים יצטרכו ללמוד תחביר חדש (TOML) ודרך חשיבה חדשה על ניהול חבילות.
• גמישות מוגבלת: ייתכן שזה לא מתאים לתהליכי בנייה מותאמים אישית הדורשים לוגיקה מורכבת.
• תלות בכלי: יהיה עליך לבחור וללמוד כיצד להשתמש במערכת בנייה ספציפית (לדוגמה, Setuptools, Poetry, Flit).

השוואת Setup.py ו-Pyproject.toml

להלן טבלה המסכמת את ההבדלים העיקריים בין setup.py ל-pyproject.toml:

אסטרטגיות הגירה: מ-Setup.py ל-Pyproject.toml

הגירה מ-setup.py ל-pyproject.toml עשויה להיראות מרתיעה, אך זוהי השקעה כדאית לתחזוקה ועקביות לטווח ארוך. הנה כמה אסטרטגיות שבהן תוכל להשתמש:

1. התחל עם Pyproject.toml מינימלי

צור קובץ pyproject.toml בסיסי המציין את מערכת הבנייה ולאחר מכן הגר בהדרגה את המטא-נתונים מ-setup.py ל-pyproject.toml.

            [build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

            

              
                Copy
              
            
          

2. השתמש ב-Setuptools עם Pyproject.toml

המשך להשתמש ב-Setuptools כמערכת הבנייה שלך, אך הגדר את מטא-נתוני הפרויקט ב-pyproject.toml. זה מאפשר לך למנף את היתרונות של pyproject.toml תוך שימוש בכלי מוכר.

3. עבר לכלי מודרני כמו Poetry

שקול לעבור לכלי מודרני כמו Poetry או Pipenv. כלים אלה מספקים תכונות מקיפות לניהול תלויות ומשתלבים בצורה חלקה עם pyproject.toml.

דוגמה: הגירה ל-Poetry

1. התקן Poetry: pip install poetry
2. אתחל Poetry בפרויקט שלך: poetry init (זה ינחה אותך ביצירת קובץ pyproject.toml)
3. הוסף את התלויות שלך: poetry add requests (או כל תלות אחרת)
4. בנה את החבילה שלך: poetry build

4. השתמש בכלים להגירה אוטומטית

כלים מסוימים יכולים לעזור להפוך את תהליך ההגירה לאוטומטי. לדוגמה, אתה יכול להשתמש בכלים כדי להמיר את קובץ ה-setup.py שלך לקובץ pyproject.toml.

שיטות עבודה מומלצות לניהול חבילות Python

1. השתמש בסביבה וירטואלית

השתמש תמיד בסביבה וירטואלית כדי לבודד את תלויות הפרויקט שלך מהתקנת ה-Python הכלל-מערכתית. זה מונע קונפליקטים ומבטיח שלפרויקט שלך יש את התלויות הנכונות.

דוגמה לשימוש ב-venv:

            python3 -m venv .venv
source .venv/bin/activate  # On Linux/macOS
.venv\Scripts\activate  # On Windows

            

              
                Copy
              
            
          

דוגמה לשימוש ב-conda:

            conda create -n myenv python=3.9
conda activate myenv

            

              
                Copy
              
            
          

2. ציין תלויות במדויק

השתמש באילוצי גרסה כדי לציין את הגרסאות התואמות של התלויות שלך. זה מונע התנהגות בלתי צפויה הנגרמת על ידי עדכוני ספריות לא תואמים. השתמש בכלים כמו pip-tools לניהול התלויות שלך.

דוגמה למפרט תלות:

            
requests >= 2.20.0, < 3.0.0

            

              
                Copy
              
            
          

3. השתמש במערכת בנייה עקבית

בחר מערכת בנייה (לדוגמה, Setuptools, Poetry, Flit) והישאר איתה. זה מבטיח בנייה עקבית בסביבות שונות ומפשט את תהליך האריזה.

4. תעד את החבילה שלך

כתוב תיעוד ברור ותמציתי לחבילה שלך. זה עוזר למשתמשים להבין כיצד להשתמש בחבילה שלך ומקל על אחרים לתרום לפרויקט שלך. השתמש בכלים כמו Sphinx כדי לייצר תיעוד מהקוד שלך.

5. השתמש באינטגרציה רציפה (CI)

הגדר מערכת CI (לדוגמה, GitHub Actions, Travis CI, GitLab CI) כדי לבנות, לבדוק ולפרוס את החבילה שלך באופן אוטומטי בכל פעם שמבוצעים שינויים בקוד שלך. זה עוזר להבטיח שהחבילה שלך תמיד במצב עבודה.

דוגמה לתצורת GitHub Actions:

            name: Python Package

on: 
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v3
    - name: Set up Python 3.9
      uses: actions/setup-python@v4
      with:
        python-version: 3.9
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install poetry
        poetry install
    - name: Lint with flake8
      run: |
        poetry run flake8 .
    - name: Test with pytest
      run: |
        poetry run pytest

            

              
                Copy
              
            
          

6. פרסם את החבילה שלך ל-PyPI

שתף את החבילה שלך עם העולם על ידי פרסומה ל-Python Package Index (PyPI). זה מקל על אחרים להתקין ולהשתמש בחבילה שלך.

שלבים לפרסום ב-PyPI:

1. הירשם לחשבון ב-PyPI וב-TestPyPI.
2. התקן twine: pip install twine.
3. בנה את החבילה שלך: poetry build או python setup.py sdist bdist_wheel.
4. העלה את החבילה שלך ל-TestPyPI: twine upload --repository testpypi dist/*.
5. העלה את החבילה שלך ל-PyPI: twine upload dist/*.

דוגמאות מהעולם האמיתי

בואו נראה כיצד כמה פרויקטי Python פופולריים משתמשים ב-pyproject.toml:

• Poetry: משתמש ב-pyproject.toml לניהול החבילות שלו.
• Black: מעצב הקוד הבלתי מתפשר משתמש גם הוא ב-pyproject.toml.
• FastAPI: פריימוורק ווב מודרני, מהיר (ביצועים גבוהים), לבניית ממשקי API עם Python, משתמש גם הוא בו.

מסקנה

pyproject.toml מייצג את הסטנדרט המודרני לניהול חבילות Python, ומציע דרך הצהרתית ומאובטחת להגדיר את מטא-נתוני החבילה שלך ולנהל תלויות. בעוד ש-setup.py שירת אותנו היטב, הגירה ל-pyproject.toml היא השקעה כדאית לתחזוקה ארוכת טווח, עקביות ואינטגרציה עם כלים מודרניים. על ידי אימוץ שיטות עבודה מומלצות ושימוש בכלים הנכונים, תוכל לייעל את זרימת העבודה של אריזת Python שלך וליצור חבילות איכותיות וניתנות לשימוש חוזר.

משאבים נוספים

• מדריך למשתמש לאריזת Python: המלצות כלים
• Pip: תמיכה ב-pyproject.toml
• Poetry: קובץ ה-pyproject.toml
• Setuptools: שימוש ב-pyproject.toml